Using Dinkey Pro/FD with PHP

If you are not already familiar with using PHP extensions, it is strongly recommended that you read the PHP documentation on the subject. The Dinkey Pro/FD SDK includes a large number of different PHP extension files. Which one(s) you need to use depends on several factors, including operating system, PHP version, architecture (e.g. x86 or x64) and thread safety. This sample code includes a script, extensionhelper.php, that detects these factors, indicates which extension is appropriate, and provides basic installation instructions.

It is important that you consider which system configuration(s) your protected software will support, and distribute the corresponding PHP extension(s). You may wish to distribute extensionhelper.php along with your software to help your users to install the correct extension for their system. See Supported Versions below for full information on the platforms supported by Dinkey Pro/FD.

Do not specify a calling program when locking the PHP extensions. The calling program for PHP code is the user's web server (or PHP CLI), which will be different for different users.

API Reference

See Modifying Your Code in the user manual for general information about the Dinkey Pro/FD API. In PHP, DDProtCheck() and the DRIS structure are not directly accessible. Instead, the PHP API provides two sets of functions: wrappers to DDProtCheck() that also take parameters that set DRIS input fields; and functions that access DRIS output fields.

Protection Check Functions

These functions each provide a wrapper to DDProtCheck() using a different function value. Each function's return value is the return value of DDProtCheck() - zero on success, or a value indicating the cause of the error on failure.

DDSimpleCheck ( int $flags ) : int

Sets the flags DRIS field and calls DDProtCheck() with the PROTECTION_CHECK function.

DDSimpleCheckEx ( int $flags , int $execs_decrement, string $alt_licence_name ) : int

Sets the flags, execs_decrement and alt_licence_name DRIS fields and calls DDProtCheck() with the PROTECTION_CHECK function.

DDSimpleCheckAlg ( int $flags , int $alg_num , int $var_a , int $var_b , int $var_c , int $var_d , int $var_e , int $var_f , int $var_g , int $var_h ) : int

Sets the flags, alg_num and var_a to var_h DRIS fields and calls DDProtCheck() with the EXECUTE_ALGORITHM function.

DDSimpleCheckAlgEx ( int $flags , int $execs_dec, string $alt_licence_name , int $alg_number , int $var_a , int $var_b , int $var_c , int $var_d , int $var_e , int $var_f , int $var_g , int $var_h ) : int

Sets the flags, execs_decrement, alt_licence_name, alg_num and var_a to var_h DRIS fields and calls DDProtCheck() with the EXECUTE_ALGORITHM function.

DDWriteString ( int $flags , int $rw_offset , string $rw_data ) : int

Sets the flags, rw_offset and rw_data DRIS fields and calls DDProtCheck() with the WRITE_DATA_AREA function.

$rw_data must be an ASCII string. To write binary data, first encode it using base64_encode(). The rw_length DRIS field is automatically set to the length of $rw_data.

DDReadString ( int $flags , int $rw_offset , int $rw_length , string &$rw_data) : int

Sets the flags, rw_offset and rw_length DRIS fields and calls DDProtCheck() with the READ_DATA_AREA function. The data read is returned in $rw_data.

Only use this function to read data that represents an ASCII string. If you read bytes that do not represent ASCII characters, the string value returned in $rw_data may be unpredictable. To read binary data, store it in the dongle data area as a base64-encoded sequence and use base64_decode() on the string returned in $rw_data.

DDGet...() Functions

Each DDGet...() function takes one parameter by reference sets it to the value of the relevant DRIS element. See Structures > DRIS Structure in the user manual for more information about the DRIS and its fields. These functions return TRUE on success, or FALSE if the internal DRIS has not been populated by a call to one of the DDProtCheck() wrapper functions above.

• DDGetExtendedError ( int &$ext_err ) : bool
• DDGetType ( int &$type ) : bool
• DDGetModel ( int &$model ) : bool
• DDGetSDSN ( int &$sdsn ) : bool
• DDGetProdCode ( string &$prodcode ) : bool
• DDGetDongleNumber ( int &$dongle_number ) : bool
• DDGetUpdateNumber ( int &$update_number ) : bool
• DDGetDataAreaSize ( int &$data_area_size ) : bool
• DDGetMaxAlgNum ( int &$max_alg_num ) : bool
• DDGetExecs ( int &$execs ) : bool
• DDGetExpDay ( int &$exp_day ) : bool
• DDGetExpMonth ( int &$exp_month ) : bool
• DDGetExpYear ( int &$exp_year ) : bool
• DDGetFeatures ( int &$features ) : bool
• DDGetNetUsers ( int &$net_users ) : bool
• DDGetAlgAnswer ( int &$alg_answer ) : bool
• DDGetFDCapacity ( int &$fd_capacity ) : bool
• DDGetFDDrive ( string &$fd_drive ) : bool
• DDGetSWKeyType ( int &$swkey_type ) : bool
• DDGetSWKeyExpDay ( int &$swkey_exp_day ) : bool
• DDGetSWKeyExpMonth ( int &$swkey_exp_month ) : bool
• DDGetSWKeyExpYear ( int &$swkey_exp_year ) : bool

PHP Example Files

• dpsample.php - various examples of using the Dinkey Pro/FD PHP API. This script outputs HTML and so is best used in a web server, but it can also be run using the PHP CLI.
• extensionhelper.php - a script that detects system configuration to determine the appropriate PHP extension to use, and where it should be located. This script outputs HTML when used in a web server and plain text when executed by the PHP CLI.

Supported Versions

The Dinkey Pro/FD SDK includes extensions for PHP versions 5.1 and newer on Windows and Linux. The x86 and x64 architectures are both supported, and extensions are provided for both Thread Safe (TS) and Non-Thread Safe (NTS) builds of PHP. Due to the large number of combinations of PHP version, OS, architecture and TS/NTS PHP builds, the exact extension for your system may not be included in the SDK. In this case, please contact us with full details of your platform.

Try It Yourself

To execute the sample code you will first need to use DinkeyAdd to produce a locked copy of the PHP extension for your system, and program a dongle (if you are using Plus or Net dongles). Place the locked extension in your PHP extensions directory. Use extensionhelper.php to determine the correct extension and the location of the extensions directory for your system.

dpsample.php gives simple examples of performing a protection check, as well as using various other features of Dinkey Pro/FD. Browse the examples at the top of dpsample.php to see how different features can be used, and uncomment the relevant lines to enable them.

Not all features are supported by all dongle models. See the user manual for more information.